[improve][misc] Migrate Swagger annotations to OpenAPI 3 (Swagger Core v3, jakarta) - #25937

Fixes #18947

PIP: PIP-472 (follow-up: completes the Swagger migration that PIP-472 explicitly deferred)

Motivation

PIP-472 migrated Pulsar from javax.* to jakarta.* but deferred the Swagger migration ("Swagger 1.x -> Swagger Core 2.x is deferred to a follow-up (decoupled, compile-/doc-only)"). Pulsar still depended on Swagger 1.6.2 (io.swagger:*), which is end-of-life, javax-era, and incompatible with the jakarta REST tier. In addition, OpenAPI document generation (the swagger.json files published as the REST API reference on pulsar.apache.org) had no equivalent in the Gradle build after the Maven removal.

This PR migrates all Swagger annotations to Swagger Core v3 (io.swagger.core.v3:swagger-annotations-jakarta:2.2.50, OpenAPI 3) and restores spec generation via the official io.swagger.core.v3.swagger-gradle-plugin.

Modifications

Annotation migration (61 Java files)

• @Api -> @Tag (+@Hidden where v1 had hidden=true), @ApiOperation -> @Operation, @ApiResponse(code=, message=, response=, responseContainer=) -> @ApiResponse(responseCode=, description=, content=) with @ArraySchema/additionalPropertiesSchema container mappings, @ApiParam -> @Parameter (bound params incl. @FormDataParam multipart parts) / @RequestBody (body params), @ApiModel/@ApiModelProperty -> @Schema with requiredMode, @Example/@ExampleProperty -> @ExampleObject.
• Map-valued responses use @Schema(type = "object", additionalPropertiesSchema = X.class) — the only form the swagger-core 2.2.50 resolver renders correctly; the @Content-level additionalPropertiesSchema = @Schema(implementation = X.class) form silently emits an empty value schema.
• Protobuf/lightproto types in @Schema(implementation=) replaced with type = "object" schemas (Jackson introspection crashes on them; those endpoints emit protobuf JSON).
• BaseGenerateDocumentation reflection ported to @Schema; removed the unused NoSwaggerDocumentation marker and stale workaround comments for swagger-core#449 / swagger-ui#558 (both fixed upstream); nested map schemas are now expressed precisely.
• Fixed malformed example JSON payloads and cleaned up typos/whitespace/grammar in annotation descriptions (separate commits).

Resolution of #18947 ("Unstable swagger output") — ExtPersistentTopics/ExtNonPersistentTopics removed

• The PartitionedTopicMetadata variant of createPartitionedTopic shares PUT /{tenant}/{namespace}/{topic}/partitions with the int variant; the OpenAPI spec forbids two operations on the same path+method, which made the Swagger 1.x output unstable — so the methods had been exiled into separate, undocumented Ext*Topics workaround classes whose implementations then drifted.
• At runtime Jersey disambiguates by content type (@Consumes("application/vnd.partitioned-topic-metadata+json")), and OpenAPI 3 expresses exactly that: one operation whose request body carries one schema per media type. The visible createPartitionedTopic operation now documents both bodies (application/json -> integer, application/vnd.partitioned-topic-metadata+json -> PartitionedTopicMetadata with partitions and properties).
• The metadata overload moved into PersistentTopics (marked @Operation(hidden = true) so the path is documented once); both overloads share a new validateAndCreatePartitionedTopic helper, which NonPersistentTopics overrides with its looser validation — the inherited metadata overload picks it up via virtual dispatch. The Ext*Topics classes are deleted (net -159 lines).

Build

• Version catalog: swagger = 2.2.50, swagger-annotations -> io.swagger.core.v3:swagger-annotations-jakarta; removed the unused swagger-core alias.
• New io.swagger.core.v3.swagger-gradle-plugin (2.2.50) configuration in pulsar-broker replicating the Maven swagger profile from branch-4.2: 7 resolve tasks with the same output file names and base info/servers, assembled by ./gradlew :pulsar-broker:generateOpenApiSpecs into build/openapi/ with the flat + v2/ + v3/ layout published on pulsar.apache.org. The plugin's default javax resolver dependencies are replaced with swagger-jaxrs2-jakarta via the swaggerDeps configuration.
• pulsar-docs-tools, pulsar-websocket and pulsar-client-tools now declare guava/commons-lang3 explicitly (previously leaked onto the compile classpath via swagger-core 1.x transitives).
• io.kubernetes:client-java's transitive Swagger 1.x annotations are excluded: they are inert metadata on the generated k8s models (verified — no Methodref/Fieldref to io.swagger in any class of either jar; the JVM ignores missing annotation types during reflection). The k8s-exercising test suites pass with the exclusion.
• Shade include pattern updated to the io.swagger.core.v3 group; LICENSE.bin.txt updated for both distributions.

Verifying this change

• Make sure that the change passes the CI checks.

This change is already covered by existing tests and verified as follows:

• The generated OpenAPI documents are operation-identical with the published 4.2.1 REST API docs: 597/597 operations across all 7 documents, zero drift; map-valued responses render the same additionalProperties value schemas as 4.2.1.
• Every annotated REST resource class in the repo (broker, functions worker, websocket, proxy) was run through the real swagger-core resolver to prove it scans cleanly (@Hidden classes excluded by design, matching 1.x behavior).
• checkBinaryLicense passes for the server and shell distributions; full compileTestJava, checkstyle, spotless and pulsar-docs-tools tests pass; the kubernetes-client-dependent test suites (pulsar-functions-runtime, pulsar-functions-secrets, pulsar-broker-auth-oidc) pass with the swagger-annotations exclusion.
• For the Unstable swagger output #18947 fix: PersistentTopicsTest passes (46/46, including the metadata-variant creation tests, now routed through PersistentTopics); two consecutive OpenAPI generation runs produce byte-identical output, confirming the reported instability is gone.

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

Dependency changes: io.swagger:swagger-annotations/swagger-core 1.6.2 removed; io.swagger.core.v3:swagger-annotations-jakarta 2.2.50 added (annotations only, no transitive deps); io.swagger:swagger-annotations excluded from io.kubernetes:client-java. REST endpoint behavior is unchanged — only the documentation annotations on the resource classes changed. As noted in PIP-472's compatibility section, authors of plugins that contribute JAX-RS resources using Swagger 1.x annotations need to migrate to io.swagger.v3.oas.annotations.* when recompiling against this version.

Assisted-by: Claude Code (Opus 4.8)